Azure Maps Route Service (preview:2024-07-01)

2025/10/23 • 2 updated methods

Route_PostSnapToRoads (updated)
Description :  This process, known as "snapping to roads", produces a series of objects that trace a path closely following the road network. The resulting data includes road names and their respective speed limits, pertinent to the traversed segments. Moreover, the Snap to Roads API offers an interpolation feature, which refines the GPS points to create a smoother route that adheres to the road's geometry. This functionality is especially beneficial for asset tracking and enhancing data visualization in mapping applications. >[!Important] > The GPS points must be within 6 kilometer of each other. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=route-v2). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/) for additional details.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Route_PostSnapToRoads",
  "$parameters": {
    "snapToRoadsRequest": {
      "$properties": [
        {
          "#name": "features",
          "Description": {
            "new": "A set of points to snap to road network. You can have a minimum of 2 points and maximum of 5000 points and the two consecutive points must be within 6 kilometer of each other and a total road distance of up to 100 kilometers. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format.\n\n`Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network.",
            "old": "A set of points to snap to road network. You can have a minimum of 2 points and maximum of 100 points and the two consecutive points must be within 6 kilometer of each other and a total road distance of up to 100 kilometers. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format.\n\n`Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network."
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /route/snapToRoads
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Indicates the account intended for use with the Microsoft Entra ID security model. This unique ID for the Azure Maps account can be obtained from the [Azure Maps management plane Account API](/rest/api/maps-management/accounts). For more information on using Microsoft Entra ID security in Azure Maps, see [Manage authentication in Azure Maps](/azure/azure-maps/how-to-manage-authentication). ,
Required: False ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/en-us/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
snapToRoadsRequest:
{
Description: Request body of SnapToRoads API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: A set of points to snap to road network. You can have a minimum of 2 points and maximum of 5000 points and the two consecutive points must be within 6 kilometer of each other and a total road distance of up to 100 kilometers. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format. `Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network. ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON Point` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details. ,
Required: True ,
}
object ,
properties:
{
Description: The properties object is required in a valid GeoJSON but it can be empty since the metadata is not used for snapping to road. ,
Required: True ,
}
object ,
}
,
]
,
interpolate:
{
Description: Specifies whether to return additional points between the snapped points to complete the full route path that smoothly follows the road geometry. The interpolated points will have `isInterpolate:true` in the response which can be used to identify the snapped points from interpolated points. ,
Required: False ,
}
boolean ,
includeSpeedLimit:
{
Description: Specifies whether to include speed limit information for the snapped points in the response. The unit is in kilometers per hour. ,
Required: False ,
}
boolean ,
travelMode:
{
Description: Specifies the routing profile for snapping the points. If unspecified, the default mode is "driving", which optimizes the snapped points for driving routes. ,
Enum:
{
driving: The points are snapped to the road suitable for cars. ,
truck: The points are snapped to the road suitable for truck. ,
}
,
Required: False ,
}
enum ,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: False ,
}
enum ,
features:
{
Description: `GeoJSON` feature object that contains Geometry object and additional properties. Refer to [RFC 7946, Section 3.2](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) for details. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteRange (updated)
Description :  A polygon boundary (or Isochrone) is returned in a counterclockwise orientation as well as the precise polygon center which was the result of the origin point. The returned polygon can be used for spatial filtering to search for features of interest within the provided Isochrone. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=route-v2). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/) for additional details.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Route_PostRouteRange",
  "$parameters": {
    "routeRangeRequest": {
      "$properties": {
        "properties": [
          {
            "#name": "distanceBudgetInMeters ",
            "Description": {
              "new": "The distance budget specifies the maximum range in meters which can be traveled from the origin waypoint. It cannot be set when `timeBudgetInSec` is specified.\n\nWhen `isSimplifiedPolygon` is false, the maximum distance supported is 90000 meters; otherwise, it is 500,000 meters.\n\nExample: \"distanceBudgetInMeters\":5000",
              "old": "The distance budget specifies the maximum range in meters which can be traveled from the origin waypoint. It cannot be set when `timeBudgetInSec` is specified.\n\nWhen `isSimplifiedPolygon` is false, the maximum distance supported is 360,000 meters; otherwise, it is 500,000 meters.\n\nExample: \"distanceBudgetInMeters\":5000"
            }
          },
          {
            "#name": "timeBudgetInSec",
            "Description": {
              "new": "The time budget specifies the maximum time in seconds available for travel, defining how far one can go within this time constraint from the origin waypoint. It cannot be set when `distanceBudgetInMeters` is specified.\n\nWhen `isSimplifiedPolygon` is false, the maximum time supported is 3600 seconds; otherwise, it is 21,600 seconds.\n\nExample: \"timeBudgetInSec\":3600",
              "old": "The time budget specifies the maximum time in seconds available for travel, defining how far one can go within this time constraint from the origin waypoint. It cannot be set when `distanceBudgetInMeters` is specified.\n\nWhen `isSimplifiedPolygon` is false, the maximum time supported is 14,400 seconds; otherwise, it is 21,600 seconds.\n\nExample: \"timeBudgetInSec\":3600"
            }
          }
        ]
      }
    }
  }
}

⚼ Request

POST:  /route/range
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Indicates the account intended for use with the Microsoft Entra ID security model. This unique ID for the Azure Maps account can be obtained from the [Azure Maps management plane Account API](/rest/api/maps-management/accounts). For more information on using Microsoft Entra ID security in Azure Maps, see [Manage authentication in Azure Maps](/azure/azure-maps/how-to-manage-authentication). ,
Required: False ,
}
string ,
routeRangeRequest:
{
Description: Request body of RouteRange API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: Specifies the `GeoJSON` Point Geometry object. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details. ,
Required: True ,
}
object ,
properties:
{
Description: Specifies the parameters to use for the calculation of isochrone polygon. ,
Required: True ,
}
{
departAt:
{
Description: The date and time of departure from the origin point formatted as a dateTime value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. If the `departAt` is not set, the default value is the current time. Example: "departAt": "2023-06-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
isSimplifiedPolygon:
{
Description: Use this to specify if you need simplified polygons that reduces the number of polygon vertices while preserving the shape. The API returns low definition polygon by default. ,
Required: False ,
}
boolean ,
optimizeRoute:
{
Description: Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" ,
Enum:
{
shortest: The route is calculated to minimize the distance. Traffic information is not used. ,
fastestWithoutTraffic: Finds the fastest route, without factoring in traffic information. ,
fastestWithTraffic: The route is calculated to minimize the time using current traffic information. `Note`: Only supported for driving and truck travelMode. ,
}
,
Required: False ,
}
enum ,
avoid:
{
Description: Specifies restrictions that the route calculation should honor when determining the reachable locations. Avoid supports multiple values in a request. Example: "avoid": ["limitedAccessHighways", "tollRoads"] ,
Required: False ,
}
[
string ,
]
,
vehicleSpec:
{
Description: Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the reachable locations. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property. ,
Required: False ,
}
object ,
distanceBudgetInMeters :
{
Description: The distance budget specifies the maximum range in meters which can be traveled from the origin waypoint. It cannot be set when `timeBudgetInSec` is specified. When `isSimplifiedPolygon` is false, the maximum distance supported is 90000 meters; otherwise, it is 500,000 meters. Example: "distanceBudgetInMeters":5000 ,
Required: False ,
}
number ,
timeBudgetInSec:
{
Description: The time budget specifies the maximum time in seconds available for travel, defining how far one can go within this time constraint from the origin waypoint. It cannot be set when `distanceBudgetInMeters` is specified. When `isSimplifiedPolygon` is false, the maximum time supported is 3600 seconds; otherwise, it is 21,600 seconds. Example: "timeBudgetInSec":3600 ,
Required: False ,
}
number ,
travelMode:
{
Description: Specifies the travel profile to consider when calculating the range polygon. If not specified, the default value is "driving". Example: "travelMode":"driving" ,
Enum:
{
driving: Routing profile suitable for cars are used for range polygon calculation. ,
truck: Routing profile suitable for commercial vehicles like trucks are used for range polygon calculation. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: False ,
}
enum ,
features:
{
Description: `GeoJSON` feature object that contains Geometry object and additional properties. Refer to [RFC 7946, Section 3.2](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) for details. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}